Banner

Banner ads occupy a small portion of the user interface, usually at the bottom or the top of the screen.

Implementation Methods

The XMediator SDK provides two ways to implement Banner ads in your React Native application:

1. Component-based Implementation: Add <XMediatorBannerView /> directly to your view hierarchy
2. Programmatic Implementation: Use the useBanner() hook to create and manage banners programmatically

Important

Do not use both Banner APIs (component-based <XMediatorBannerView /> and programmatic useBanner()) simultaneously in the same application. Choose one implementation method and use it consistently throughout your app.

Method 1: Component-based Implementation

Add the <XMediatorBannerView /> component directly to your view hierarchy. The banner will be positioned using standard React Native layout.

Important notes:

• The banner will start loading automatically when the component mounts - there's no need to manually call create() or load() like in the programmatic implementation
• The banner starts hidden by default, so you must call show() when you want it to be visible

Basic Usage

import React, { useRef } from 'react';
import { View } from 'react-native';
import {
  XMediatorBannerView,
  BannerSize,
} from "react-native-xmediator";

export default function App() {
  const bannerRef = useRef(null);

  return (
    <View style={{ flex: 1 }}>
      {/* Your app content */}
      
      <XMediatorBannerView
        ref={bannerRef}
        placementId="<placement-id>"
        size={BannerSize.Phone}
        adSpace="demo_app_banner_screen"
        style={{
          margin: 16,
        }}
      />
    </View>
  );
}

Component Props

Prop	Type	Required	Description
placementId	string	Yes	The placement ID for the banner
size	BannerSize	Yes	Size of the banner (Phone, Tablet, MREC)
adSpace	string	No	Ad space name for tracking purposes
style	ViewStyle	No	Standard React Native style for positioning
ref	Ref	No	Reference to call show() and hide() methods

Using Banner Ref Methods

If you need to programmatically show or hide the banner, you can use the ref:

import React, { useRef } from 'react';
import { View, Button } from 'react-native';
import {
  XMediatorBannerView,
  BannerSize,
} from "react-native-xmediator";

export default function App() {
  const bannerRef = useRef(null);

  const showBanner = () => {
    bannerRef.current?.show();
  };

  const hideBanner = () => {
    bannerRef.current?.hide();
  };

  return (
    <View style={{ flex: 1 }}>
      <Button title="Show Banner" onPress={showBanner} />
      <Button title="Hide Banner" onPress={hideBanner} />
      
      <XMediatorBannerView
        ref={bannerRef}
        placementId="<placement-id>"
        size={BannerSize.Phone}
        adSpace="demo_app_banner_screen"
        style={{
          alignSelf: 'center',
          marginTop: 20,
        }}
      />
    </View>
  );
}

Method 2: Programmatic Implementation

Use the useBanner() hook to create and manage banners programmatically. The banner will be positioned automatically based on the position parameter.

Basic Usage

Start creating a banner

import React, { useEffect } from 'react';
import {
  BannerPosition,
  BannerSize,
  useBanner,
} from "react-native-xmediator";

export default function App() {
  const { create, hide, show, isShowing } = useBanner();

  useEffect(() => {
    create({
      placementId: "<placement-id>",
      size: BannerSize.Phone,
      position: BannerPosition.Bottom,
    });
  }, []);

  return <>{/* your app code... */}</>;
}

tip

If you are using expo tabs, you can use useFocusEffect to fire on focus.

Showing a banner

import React, { useEffect } from 'react';
import {
  BannerPosition,
  BannerSize,
  useBanner,
} from "react-native-xmediator";

export default function App() {
  const { create, hide, show, isShowing } = useBanner();

  useEffect(() => {
    create({
      placementId: "<placement-id>",
      size: BannerSize.Phone,
      position: BannerPosition.Bottom,
    });
    show("<placement-id>");
  }, []);

  return <>{/* your app code... */}</>;
}

note

In this case we are showing the banner after creating it. You can also show on another event, just call show().

Built-in features

Banner autorefresh

After being displayed for some time, our banner fires a Load() call automatically to refresh its contents. You can configure this time through our Admin tool for each one of your banners.

Banner retry

Our banner has a built in auto retry for failed loads attempts. This means that when a banner fails to load, it will retry again until it loads successfully. Time between each retry attemp will increase using an exponential backoff. You should not add any retry logic on your end, as it may interefere with our retry behaviour.

Hiding a banner

Use this function to indicate that the banner should not be visible. This will not interfere with the loading process, so if the banner is still being loaded it will continue to do so.

import {
  BannerPosition,
  BannerSize,
  useBanner,
  useRewarded,
  useRewardedEvents,
} from "react-native-xmediator";

export default function App() {
  const { create, hide, show, isShowing } = useBanner();

  // use effect to create when component mounts
  // if you are using expo tabs, you can use useFocusEffect to fire on focus.
  useEffect(() => {
    create({
      placementId: "<placement-id>",
      size: BannerSize.Phone,
      position: BannerPosition.Bottom,
    });
    show();
    return () => {
      // hide when component unmounts
      hide("<placement-id>");
    };
  }, []);

  return <>{/* your app code... */}</>;
}

note

You can also hide on another event, just call hide().

Banner Sizes

Constant	Size (WxH)	Description
Phone	320x50	Size for banners used in phone devices
Tablet	728x90	Size for banners used in tablet devices
MREC	300x250	Size for IAB Medium Rectangle banners

Size is in DP for Android and Points for iOS.

Banner Position

Constant	Description
Top	Places the banner at the top of the screen
Bottom	Places the banner at the bottom of the screen
Custom	Custom x,y position relative to top-left corner

Setting a banner's position

const { setPosition } = useBanner();

setPosition("<placement-id>", BannerPosition.Top);

Additional settings

Register Ad Callbacks

Both implementation methods support the same callback events. Every ad callback indicates the placement id of the banner that triggered the event:

import { useBannerEvents } from "react-native-xmediator";

useBannerEvents(
  {
    onLoaded: (placementId, loadResult) => {
      console.log("banner loaded", placementId, loadResult);
    },
    onClicked: (placementId) => {
      console.log("banner clicked", placementId);
    },
    onImpression: (placementId, impressionData) => {
      console.log("banner impression", placementId, impressionData);
    },
  },
  []
);

(Optional) Updating ad space

Before showing an ad, you can set an ad space name for the banner instance. This is useful for tracking purposes because it enables you to get performance insights for different ad spaces of your application.

const { setAdSpace } = useBanner();

setAdSpace("<placement-id>", "banner-ad-space");

(Optional) Manually refreshing a banner ad

Banner ads usually refresh their contents automatically, after a certain amount of time has passed. However, if you prefer to, you can manually refresh a banner's content by calling the load method:

const { load } = useBanner();

load("<placement-id>");

Complete Examples

Component-based Example

ComponentBannerExample.tsx

ComponentBannerExample.tsx

import React, { useRef } from 'react';
import { Button, Text, View, StyleSheet } from "react-native";
import {
  XMediatorBannerView,
  BannerSize,
  useBannerEvents,
} from "react-native-xmediator";

const demoPlacementId = "<placement-id>";

export function ComponentBannerExample() {
  const bannerRef = useRef(null);

  useBannerEvents(
    {
      onLoaded: (placementId, loadResult) => {
        console.log("[Demo App] banner loaded", placementId, loadResult);
      },
      onClicked: (placementId) => {
        console.log("[Demo App] banner clicked", placementId);
      },
      onImpression: (placementId, impressionData) => {
        console.log("[Demo App] banner impression", placementId, impressionData);
      },
    },
    []
  );

  const showBanner = () => {
    bannerRef.current?.show();
  };

  const hideBanner = () => {
    bannerRef.current?.hide();
  };

  return (
    <View style={styles.container}>
      <Text>Component-based Banner Example</Text>
      
      <View style={styles.buttonContainer}>
        <Button title="Show Banner" onPress={showBanner} />
        <Button title="Hide Banner" onPress={hideBanner} />
      </View>

      <XMediatorBannerView
        ref={bannerRef}
        placementId={demoPlacementId}
        size={BannerSize.Phone}
        adSpace="demo_app_banner_screen"
        style={styles.banner}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 16,
  },
  buttonContainer: {
    flexDirection: 'row',
    justifyContent: 'space-around',
    marginVertical: 20,
  },
  banner: {
    alignSelf: 'center',
    marginTop: 20,
  },
});

Programmatic Example

ProgrammaticBannerExample.tsx

ProgrammaticBannerExample.tsx

import React, { useEffect } from 'react';
import { Button, Text, View } from "react-native";
import {
  useBanner,
  BannerSize,
  BannerPosition,
  useBannerEvents,
} from "react-native-xmediator";

const demoPlacementId = "<placement-id>";

export function ProgrammaticBannerExample() {
  const { create, hide, show, isShowing, setPosition } = useBanner();

  useEffect(() => {
    create({
      placementId: demoPlacementId,
      size: BannerSize.Phone,
      position: BannerPosition.Bottom,
    });
    show(demoPlacementId);
    
    return () => {
      hide(demoPlacementId);
    };
  }, []);

  useBannerEvents(
    {
      onLoaded: (placementId, loadResult) => {
        console.log("[Demo App] banner loaded", placementId, loadResult);
      },
      onClicked: (placementId) => {
        console.log("[Demo App] banner clicked", placementId);
      },
      onImpression: (placementId, impressionData) => {
        console.log("[Demo App] banner impression", placementId, impressionData);
      },
    },
    []
  );

  return (
    <View style={{ marginBottom: BannerSize.Phone.height }}>
      <Text>Programmatic Banner Example</Text>
      <Button title="Show Banner" onPress={() => show(demoPlacementId)} />
      <Button title="Hide Banner" onPress={() => hide(demoPlacementId)} />
      <Button
        title="Set Banner on Bottom"
        onPress={() => setPosition(demoPlacementId, BannerPosition.Bottom)}
      />
      <Button
        title="Set Banner on Top"
        onPress={() => setPosition(demoPlacementId, BannerPosition.Top)}
      />
      <Text>Is Banner Showing: {isShowing ? "Yes" : "No"}</Text>
    </View>
  );
}